home *** CD-ROM | disk | FTP | other *** search
/ Linux Cubed Series 2: Applications / Linux Cubed Series 2 - Applications.iso / utils / file / logiso.000 / logiso / Utils / README < prev    next >
Encoding:
Text File  |  1995-03-24  |  13.1 KB  |  388 lines
  1. /usr/src/linux/fs//Utils/README
  2. logiso - isofs, iso-9660 file activity logging
  3. Author: Michael Coulter        coulter@cup.hp.com
  4. (C) Copyright 1995 by Michael Coulter.  All rights reserved.
  5.  
  6. Overview:
  7. Installation:
  8.    Kernel changes:
  9.       Turning off logging:
  10.    Logiso utilities:
  11.       Setting up find_links:
  12.       The config file:
  13.       The cd_files file:
  14.       Setting up the mirror directory:
  15.       Environment variables:
  16. Using the logiso utilities:
  17.    Using logiso_copy:
  18.    Using logiso_get:
  19.    Using logiso_init:
  20.    Using logiso_preview:
  21.    Using logiso_stop:
  22. Copying:
  23. Disclaimer:
  24. Acknowledgements:
  25. History:
  26. Bugs:
  27.  
  28.  
  29. Overview:
  30.  
  31.    In most of what follows, it is presumed that you are executing commands
  32.    as root.
  33.  
  34.    This package provides a facility to help you migrate to a hard disk
  35.    the files which you use on a cd-rom and use symbolic links for the
  36.    files which you don't use.
  37.  
  38.    The logiso package contains changes to make to the isofs file system
  39.    to provide logging of disk activity on an iso-9660 cd-rom file system.
  40.    The package also contains utilities to migrate logged files to your
  41.    hard disk.
  42.  
  43.    The logging facility is on by default, but you can use an ioctl call
  44.    to turn off logging and free up the kernel buffers (about 40K).  See
  45.    "Kernel changes".  The logiso_stop command can be used to turn off
  46.    logging.
  47.  
  48.    Once you have installed it, a typical usage scenario would be:
  49.  
  50.       1. You perform an operation and notice cd-rom activity.  You decide
  51.          that you want to be able to do this operation without accessing
  52.          the cd-rom.
  53.  
  54.       2. Clear the existing log so that you won't install other files.
  55.          This will also start logging if it was turned off.
  56.          Execute:
  57.  
  58.              logiso_get /mount/path/cd-rom > /dev/null
  59.  
  60.          or (slower to execute, but easier to type):
  61.  
  62.              logiso_preview > /dev/null
  63.  
  64.       3. Perform the operation again.  Even though the cd-rom light doesn't
  65.          go on because the blocks are in the memory buffer, the cd-rom 
  66.          file activity is still logged.
  67.  
  68.       4. If you want to see what you are going to install, execute:
  69.  
  70.               logiso_preview 
  71.  
  72.          to print a list of the files and directories that will be copied
  73.          to your hard disk.  This empties the log, so you must repeat 
  74.          step 3 before proceeding with step 5.
  75.  
  76.       5. Install the files which were logged:
  77.  
  78.               logiso_copy
  79.  
  80.  
  81. Installation:
  82.  
  83.    First make sure that the following commands are already installed
  84.    on your hard disk or the logiso_copy script will fail in the middle
  85.    of installation when it tries to install a command:
  86.  
  87.        cp
  88.        ln
  89.        mkdir
  90.        mv
  91.        rm
  92.  
  93.    Also, add /usr/src/linux/fs/isofs/Utils to your (and root's) path string.
  94.  
  95.    Installing the distributed files:
  96.  
  97.       Unpack the tar file while in the /usr/src/linux/fs/isofs directory.
  98.       The directories RCS and Utils will be created.  
  99.  
  100.       Follow the directions in the subsections below to complete the
  101.       installation.
  102.  
  103.    Kernel changes:
  104.  
  105.       The kernel changes implement three ioctl calls for the isofs file
  106.       system (used to access iso-9660 file systems on a cd-rom).  The
  107.       three calls are:
  108.  
  109.      ISO_IOC_GETLOGSIZE returns the size of the buffer returned by
  110.            ISO_IOC_READLOG.  It also starts logging if it was off.
  111.  
  112.      ISO_IOC_READLOG is given a pointer to a buffer and fills that buffer
  113.            with log information.  See ioctl.c and iso_fs.h and
  114.            logiso_get.c.
  115.  
  116.      ISO_IOC_STOPLOG turns off logging and frees up the kernel buffers
  117.            (about 40K bytes) which hold the log information.
  118.  
  119.  
  120.       The logging facility is initially on, but the kernel buffers are
  121.       only allocated when the first event is logged.
  122.  
  123.       Compare your source files against the base versions of the files
  124.       with rcs histories in /usr/src/linux/fs/isofs/RCS.  If the files
  125.       are the same, you can use the last version of the file.  If not,
  126.       make the corresponding changes in your files.  ioctl.c is a new
  127.       file.
  128.  
  129.       Re-compile the kernel and boot with the new kernel after reading
  130.       the following section, "Turning off logging".
  131.  
  132.       Turning off logging:
  133.  
  134.          Once you have gotten settled in, you will want to arrange to
  135.          turn off logging after your system has re-booted.  Here
  136.          are the lines that I added to /etc/rc.d/rc.local:
  137.  
  138.             # Turn off logging after waiting for the boot process to quiet down.
  139.             if [ 0 = 0 ]
  140.             then
  141.             (sleep 20
  142.              /usr/src/linux/fs/isofs/Utils/logiso_get -v > /tmp/last_isolog 2>&1
  143.              /usr/src/linux/fs/isofs/Utils/logiso_stop >> /tmp/last_isolog 2>&1
  144.         ) &  > /dev/null 2>&1
  145.         fi
  146.  
  147.          The "0 = 0" test makes it easy to turn this code off by changing
  148.          the test to "0 = 1".
  149.  
  150.  
  151.    Logiso utilities:
  152.  
  153.       In the /usr/src/linux/fs/isofs/Utils directory, execute:
  154.  
  155.               make
  156.  
  157.       Setting up find_links:
  158.  
  159.          The find_links script is used by the check_links script to
  160.          find symbolic links.  If you want to execute find_links
  161.          against "/", you may need to edit find_links to prune certain
  162.          directories on your system or make your own find_links script
  163.          and enter its path in the config file.
  164.  
  165.       The config file:
  166.  
  167.      Edit the file config to match your system requirements.
  168.  
  169.      Basically you need to tell the utilities where the cd-rom is
  170.      mounted and what directory will mirror the cd-rom.
  171.  
  172.      I recommend that you use a dedicated directory to mirror the
  173.      cd-rom rather than using the root directory to mirror the
  174.      cd-rom.  It will make it easier to account for disk space usage
  175.      and to back out decisions you make to migrate files to your
  176.      hard disk.
  177.  
  178.      Here is the setup I use:  The Walnut Creek CD-ROM edition of
  179.      Yggdrasil Plug-and-Play Linux installs itself with /system_cd
  180.      as the mount point of the cd-rom.  I moved the mount point to
  181.      /cdmnt and made /system_cd the mirror directory.  It is a good
  182.      idea to have the mount point in the same directory as the
  183.      original mount point so that relative paths like
  184.      ../../var will get to the right place.
  185.  
  186.      The basic scheme is that the only links to the cd-rom are from
  187.      paths or directories below the mirror directory to the real
  188.      file or directory (not a link) on the cd-rom.  All other
  189.      links go through the mirror directory.
  190.  
  191.      If you have multiple cd-rom drives or want to mirror different
  192.      cd volumes with separate mirror directories, you can have
  193.      different config files with different prefixes.  The commands
  194.      which use the config file have an optional pair of parameters:
  195.  
  196.          -d config_prefix
  197.  
  198.          For example,
  199.  
  200.              logiso_copy -d m2
  201.  
  202.          would use the m2config config file which could specify a different
  203.          mount point, mirror directory and cd_files file.
  204.  
  205.       The cd_files file:
  206.  
  207.          The cd_files file contains a list of all the files on the
  208.          cd-rom and the inode number of each file.  The path to the
  209.          cd_files file is set in the config file.  In the config file
  210.          provided, the name of the file is "cd_files" in the isofs/Utils
  211.          directory.
  212.  
  213.          If you are want to save disk space, you can compress the
  214.          cd_files file with gzip.  It will be uncompressed for use.
  215.          This will take some time.  If you are using logiso_copy
  216.          frequently, you will want to uncompress the file.
  217.  
  218.       Setting up the mirror directory:
  219.  
  220.          Once you have set up the config file, you can initialize the
  221.          mirror directory by executing:
  222.  
  223.              logiso_init
  224.  
  225.          WARNING: logiso_init will remove the mirror directory and 
  226.          everything below it (unless your mirror directory is "/").
  227.  
  228.          Logiso_init will create the mirror directory and populate it
  229.          with symbolic links to everything in the cd mount point.
  230.  
  231.          You are now ready to use the utilities.  See the scenario in the
  232.          "Overview" section and the descriptions in the following
  233.          "Using the logiso utilities" section.
  234.  
  235.  
  236. Using the logiso utilities:
  237.  
  238.    Read over the scenario described in the "Overview" section. 
  239.  
  240.    Note that the log will only hold about 5,000 entries.  The log is
  241.    flushed when it fills, so don't try to do too much work before
  242.    you use logiso_copy.  In any case, you can repeat the operation
  243.    and logiso_copy to get files that were missed on the first round.
  244.  
  245.    See the section, "The config file" for a discussion of the 
  246.    "-d config_prefix" option which appears in a number of the commands.
  247.  
  248.  
  249.    Using logiso_copy:
  250.  
  251.       USAGE: logiso_copy [ -d config_prefix ]
  252.  
  253.       Copies the files or directories of the logged inodes to the 
  254.       corresponding location below the mirror directory.
  255.  
  256.       This command will empty the log.  It will also turn on logging
  257.       if it was turned off with logiso_stop.
  258.  
  259.  
  260.    Using logiso_get:
  261.  
  262.       USAGE: logiso_get  [ -v ] cd_mount_point [ log_file ]
  263.  
  264.       Get the isofs usage log and place it in log_file.  The log is written
  265.       to stdout if log_file is not given.
  266.  
  267.       This command will empty the log.  It will also turn on logging
  268.       if it was turned off with logiso_stop.
  269.  
  270.  
  271.    Using logiso_init:
  272.  
  273.       USAGE: logiso_init [ -d config_prefix ]
  274.  
  275.       Initialize the mirror directory to mirror the top level of the
  276.       mount point directory.
  277.  
  278.       WARNING: logiso_init will remove the mirror directory and 
  279.       everything below it (unless your mirror directory is "/").
  280.  
  281.  
  282.    Using logiso_preview:
  283.  
  284.       USAGE: logiso_preview  [ -d config_prefix ]
  285.  
  286.       List the files that would have been installed by logiso_copy.
  287.       This command will empty the log.  It will also turn on logging
  288.       if it was turned off with logiso_stop.
  289.  
  290.  
  291.    Using logiso_stop:
  292.  
  293.        USAGE: logiso_stop  cd-mount-point-or-file
  294.  
  295.        Stop the logging system.  Deallocate the kernel buffers in which
  296.        the log is kept.
  297.  
  298. Copying:
  299.   
  300.    Everyone is granted permission to copy and redistribute the files in
  301.    this package provided:
  302.       
  303.         1. No changes are made to any of the files in the distribution and
  304.            all of the files are provided in any copy.
  305.  
  306.     2. No charge is made for this software.  This clause shall not  
  307.        be construed as constraining other software distributed on
  308.        the same medium as this software, nor is a distribution fee
  309.        considered a charge.
  310.  
  311. Disclaimer:
  312.  
  313.    This package is provided as-is.  Michael Coulter makes no express or
  314.    implied warranty of any kind with respect to this package.  Michael
  315.    Coulter shall not be liable for any direct indirect, special, incidental
  316.    or consequential damages (whether based on contract, tort or any other
  317.    legal theory) arising in any way from use of any part of this package.
  318.  
  319. Acknowledgements:
  320.  
  321.    Cam Johnson for suggesting that some users might want the cd_files
  322.    file to be compressed to save space and for looking over the
  323.    implementation.
  324.  
  325. History:
  326.  
  327.    0.1  Initial version exposed to a handful of people.
  328.  
  329.    0.2 * Allow the cd_files file to be compressed to save disk space.
  330.  
  331.        * Support multiple cd-rom drives and/or multiple mirror directories
  332.          with the following features:
  333.  
  334.       * Add the device number in addition to the inode number to
  335.         each log entry.  Provide the device number accessed in the
  336.         header information.  Logiso_get (and therefore logiso_copy
  337.         and logiso_preview) only reports the files on the device
  338.         indicated by mount point.
  339.  
  340.       * Add -d option to logiso_copy and logiso_preview to conveniently
  341.         support multiple cd-rom's or separate mirror directories.   
  342.  
  343.    0.3 * Added copyright notices.  Copying policy and disclaimer in README.
  344.    
  345. Bugs:
  346.  
  347.    Sometimes accesses to a directory will continue to be logged after
  348.    the directory has been mirrored with a directory of symbolic links.
  349.  
  350.    My best guess is that in some cases, a link to a file on the 
  351.    cd-rom results in an access to the directory on the cd-rom which
  352.    contains the file.  Replacing the link with a copy of the
  353.    file (or a directory filled with links if the file is a directory)
  354.    eliminates the access to the cd-rom.  The hard part is figuring out
  355.    which file is involved because only the directory containing it is
  356.    logged.
  357.  
  358.    1.  /mnt/system_cd/usr/lib/emacs/19.25/lisp/term/x-win.elc showed up
  359.        in the log, but after it was installed, the link
  360.        /mnt/system_cd/usr/lib/emacs/19.25/lisp/term/x-win.el was  causing
  361.        a cd-rom access but only its directory was logged.
  362.  
  363.        This seems to be a general property.  I have added a kludge to
  364.        mirror a .el file (if it exists) when a .elc file is mirrored in.
  365.  
  366.    2. Files which were not logged but which resulted in accesses to the
  367.       directory which contained them:
  368.  
  369.       Simple files:
  370.  
  371.         WHAT                        WHY
  372.         =====================                ==========
  373.         *.el files as from note #1.            emacs
  374.           /system_cd/usr/bin/look                emacs
  375.           /system_cd/usr/dict/words            emacs
  376.           /system_cd/usr/lib/emacs/19.25/etc/GNU        emacs
  377.  
  378.       Directories:
  379.  
  380.         /system_cd/usr/packages/interviews/bin/LINUX    PATH string
  381.     /system_cd/usr/lib/emacs/19.25/i486-linux    emacs
  382.     /system_cd/usr/packages/sound/man        MANPATH
  383.     /system_cd/usr/packages/pbm/man            MANPATH
  384.     /system_cd/usr/packages/openwin/man        MANPATH
  385.     /system_cd/usr/packages/interviews/man        MANPATH
  386.     /system_cd/usr/packages/andrew/man        MANPATH
  387.     /system_cd/usr/X11/man                MANPATH
  388.